 /***************************************************************************************************
  * Copyright (c) 2006 IBM Corporation and others. All rights reserved. This program and the
  * accompanying materials are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
  * http://www.eclipse.org/legal/epl-v10.html
  *
  * Contributors: IBM Corporation - initial API and implementation
  **************************************************************************************************/

 package org.eclipse.ui.intro.config;

 import java.util.Map ;

 import org.eclipse.ui.internal.intro.impl.IntroPlugin;
 import org.eclipse.ui.intro.IIntroSite;


 /**
  * Classes that extend this abstract class are used to configure <code>CustomizableIntroPart</code>.
  * Since it is possible for multiple products to use the same intro configuration, this class allows
  * them to customize some aspects of the intro content so that it looks different for different
  * products even though they all share the same intro implementation and content.
  *
  * @since 3.2
  */

 public abstract class IntroConfigurer {

     /**
      * The identifier of the named group where the configurer can contribute local tool bar actions.
      *
      * @see #init(IIntroSite, Map)
      */
     public static final String TB_ADDITIONS = "additions"; //$NON-NLS-1$

     protected Map themeProperties;
     protected IIntroSite site;

     /**
      * Provides the opportunity for the configurer to contribute to the action bars and to fetch
      * presentation theme properties.
      *
      * @param site
      * the intro part's site
      * @param themeProperties
      * properties of the current theme that can be used by the configurer, or
      * <code>null</code> if no theme is currently active or the active theme has no
      * properties.
      */
     public void init(IIntroSite site, Map themeProperties) {
         this.themeProperties = themeProperties;
         this.site = site;
     }

     /**
      * Returns the value of the theme property with a given name.
      *
      * @param name
      * the theme property name
      * @return the value of the property or <code>null</code> if property is not found, the theme
      * does not have properties or no theme is currently active.
      */

     protected String getThemeProperty(String name) {
         if (themeProperties == null)
             return null;
         String value = (String )themeProperties.get(name);
         if (value!=null)
             value = IntroPlugin.getDefault().getIntroModelRoot().resolveVariables(value);
         return value;
     }

     /**
      * Returns the value of the variable defined by the configurer. This variable can appear in XML
      * content files in attribute names and values of elements. Whenever $variable$ is encountered
      * in the content, it is evaluated using this class by passing 'variable' to this method and
      * substituting the result in the content.
      *
      * @param variableName
      * the name of the substitution variable
      * @return the value to substitute in place of a variable or <code>null</code> if the variable
      * cannot be resolved.
      */
     public abstract String getVariable(String variableName);

     /**
      * Returns the children of computed groups. Groups marked as computed will be completed at run
      * time when the group is asked to provide children.
      *
      * @param pageId
      * the identifier of the page in which this group appears
      * @param groupId
      * the identifier of the group group within the page
      * @return an array of intro elements for this group. Each intro element should contain only
      * legal elements and attributes according to the intro content schema. Returns an empty
      * array for no children.
      */
     public abstract IntroElement[] getGroupChildren(String pageId, String groupId);

     /**
      * Returns an array of elements that will be used to build launch bar short cut links. Override
      * this method if the intro launch bar has been marked as computed.
      *
      * @return an array of elements that will be used to dynamically build shortcut links.
      */
     public IntroElement[] getLaunchBarShortcuts() {
         return new IntroElement[] {};
     }

     /**
      * Resolves an incomplete path in the form "page_id/@" where page_id represents the identifier
      * of the target page. The configurator should complete the path according to its internal
      * resolution mechanism. The final path must point at an anchor in the referenced page.
      *
      * @param extensionId
      * the id specified for the config extension
      * @param path
      * the incomplete path specified for the config extension
      * @return the complete path that points at the anchor element in the referenced page, or
      * <code>null</code> if the path cannot be resolved or the extension should be hidden.
      */
     public abstract String resolvePath(String extensionId, String path);

     /**
      * Returns the style value that will be mixed in with the original style of the extension.
      * Themes can use this feature to render certain extensions differently.
      *
      * @param pageId
      * the identifier of the target page that this extension is contributed into
      * @param extensionId
      * the identifier of the extension to provide the mixin style for.
      * @return the style to add to the original extension style or <code>null</code> if no mixin
      * style is found for this extension.
      */
     public String getMixinStyle(String pageId, String extensionId) {
         return null;
     }
 }
